###############################################################################
This capsule produces the numerical results and simulations supporting the
Appendix for "The Probability of Casting a Pivotal Vote in an Instant
Runoff Voting Election" by Samuel Baltz. Work on this script was begun in
the spring and summer in Cambridge, MA in 2022, and completed there in early
fall of 2024.

The core script is simulate_pivotality.py, and its sole dependency is
skellam.py, which defines the skellam PDF and CDF computations used to
estimate pivot probabilities in this paper.

Any questions or comments should be directed to sbaltz@umich.edu.
###############################################################################


BEFORE YOU REPLICATE:
-------------------------------------------------------------------------------
RUNTIME WARNING: The full replication with 100 runs takes about 5.5 hours on a
    machine with 16GB RAM and a 2.5GHz Intel i7 CPU.

Size on Disk: If you select 100 runs, it will save about 300 KB to disk, in the
  form of two image files.

RAM: The simulation should take about 0.5 GB of RAM at any given moment.

Software versions: This code was most recently tested on Python 3.8.10.
-------------------------------------------------------------------------------


WHAT IS BEING REPLICATED:
-------------------------------------------------------------------------------
The facts that are printed to console replicate the in-text claims from
Appendix Section 5.

simulated_probabilities_power.png replicates Appendix Figure 1. a)
simulated_probabilities_uniform.png replicates Appendix Figure 1. b)

NOTE:
By default, for the sake of reasonable runtime, I have reduced the number of
runs called in this capsule to 1. Please see ``STEPS TO REPLICATE'' for
instructions on fully replicating the Appendix figures.
-------------------------------------------------------------------------------


STEPS TO REPLICATE:
-------------------------------------------------------------------------------
IF ON CODE OCEAN:
1. Click "Reproducible Run"

IF NOT ON CODE OCEAN:
1. Download the capsule from Code Ocean
2. Make sure there is a top-level directory called results/ alongside code/
3. If you wish to replicate all 100 runs, edit simulate_pivotality.py and set
    NUM_RUNS = 100
4. Set your directory to PRODUCTION_CODE, and run:
> python3 simulate_pivotality.py
-------------------------------------------------------------------------------


FILE STRUCTURE:
-------------------------------------------------------------------------------
REPLICATION_CODE
  |____enviroment
      |____README.txt
  |____src/
      |____simulate_pivotality.py
      |____skellam.py
  |__results/   
      |____[all results go here]
-------------------------------------------------------------------------------
